Description

In this example, the TRIDENT's document signature API is used to sign a PDF document using a digital signature (PKCS #1) generated by a system other than the TRIDENT platform that performs the signature. This situation occurs in all deployments in which, for reasons of confidentiality, the digital signature provider cannot access the documents that it signs (e.g., because it is located in another organization).

The PDF signature is requested by an application registered in the TRIDENT (txeidas.safelayer.com) as an OAuth 2.0 client application, which means it has an identifier (docsign_orchestrator) and shares a secret with the platform (demodemo). Furthermore, this application is associated to an authorization server (esignsp) capable of issuing access tokens that will allow the application to perform the document signature operations. I.e., the application is associated to an authorization server that recognizes the urn:safelayer:eidas:sign:process:document scope and supports client credentials grant flows. The PDF document is signed in six steps:

1. Obtaining the token for accessing the signature operations

2. Creating the document and signature definitions resource

3. Obtaining the hash of the document

4. Obtaining the digital signature of the document

5. Inserting the digital signature in the document.

6. Obtaining the signed document

Lastly, after the signature is performed, the document and signature definitions resource used is deleted.

Obtaining the Token for Accessing the Signature Operations

Firstly, the docsign_orchestrator application sends the following message to the TRIDENT to obtain the access token for accessing the PDF document signing operations (see the Obtain a Token operation):

Note that the application must use its identifier and the secret it shares with the TRIDENT to authenticate in accordance with the HTTP basic authentication scheme (RFC 2617). Also note that the application specifies that its authentication also demonstrates having the right to obtain the access token requested (grant_type=client_credentials).

The access token is finally obtained in the following HTTP response:

This token must be included in the Authorization header of all request messages subsequently sent to the TRIDENT for signing the PDF document in accordance with RFC 6750.

Creating the Document and Signature Definitions Resource

The docsign_orchestrator application requests the creation of a document and signature definitions resource by sending the following message to the TRIDENT's signature services provider (see the create a document and signature definitions resource operation and note that, for the sake of readability, the binary content of the PDF document has been replaced with {pdfToBeSigned}).

In the above message you can see that:

• Only one signature definition is provided (i.e., the document is to be signed only once).

• A PAdES-BES (parameters.type = "pades-bes") signature is to be performed, and the SHA-256 hash algorithm (parameters.default_digest_algorithm = "sha256") is to be used for calculating the digital signature.

• The signature has an appearance (parameters.signature_field.appearance) and is located on the last page of the document (parameters.signature_field.location.page.number = "last").

• The signature appearance comprises an image with text to the right: the distinguished name of the signer and the date and time the signature was made (parameters.signature_field.appearance.signature_details.details[0].type = "subject", parameters.signature_field.appearance.signature_details.details[1].type = "location" and parameters.signature_field.appearance.signature_details.details[2].type = "date").

• Madrid, Spain is indicated as the place where the signature was generated (parameters.location = "Madrid, Spain").

If the request is successfully processed, the TRIDENT creates the document and signature definitions resource requested and responds to the application with the following HTTP message:

Where the document and signature definitions resource created has the identifier dc_11dbed1a0e9f0cc and contains, in addition to the document to be signed, the signature definition with the identifier sd_f9c2d467a2bf72c7.

Obtaining the Hash of the Document

The docsign_orchestrator obtains the hash of the document to be signed prior to the obtaining of the digital signature to be applied to it. To do this, it sends the following message to the TRIDENT's signature services provider that includes the signer's certificate (see the obtain the hash of the document in accordance with a signature definition operation). This is because a PAdES-BES signature is to be performed, which requires including the signer's certificate among the attributes signed along with the content of the PDF document itself.

TRIDENT calculates the SHA-256 hash of the PDF document (and of the attributes to be signed with it) and responds with the following message:

Obtaining the Digital Signature of the Document

Once the hash of the document has been obtained, the signdoc_orchestrator requests that a digital signature provider separate from the TRIDENT platform generate the digital signature on the document to be signed. To do this, the signdoc_orchestrator application must provide to the digital signature provider the hash of the document obtained in the previous step ( NDky...cwNQ== ) and also indicate to it which signature key must be used for generating the signature. This last step is certain to require the intervention of the user, not only for selecting the key but also for authorizing its use for generating the digital signature. In all cases, both this interaction with the user and the interaction with the digital signature provider for obtaining the PKCS #1 signature takes place outside of the TRIDENT.

Inserting the Digital Signature in the Document

After obtaining the digital signature of the PDF document, the application inserts it in the document by sending the following message to the TRIDENT's signature services provider (see the updating a signature definition operation):

To which TRIDENT responds with the following message:

Obtaining the Signed Document

After receiving the above message, the application sends the following message to the TRIDENT's signature services provider to obtain the signed PDF document (see the obtain a document operation):

Note that the URL of the document requested is created by adding /content to the URL specified in the response received when the document and signature definitions resource was created (the Location header of the response, the self property of the JSON object contained in the response).

Lastly, the application receives the signed document in the following HTTP response message (note that, for the sake of readability, {pdfSigned} replaces the binary content of the signed PDF).

Deleting the Document and Signature Definitions Resource

After receiving the signed PDF document, the application sends the following message to the TRIDENT's signature services provider to delete the document and signature definitions resource used (see the delete a document and signature definitions resource operation):

TRIDENT deletes the resource specified in the request and responds with the following message: